{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting Started with LlamaCloud Indexing\n",
    "\n",
    "This notebook is a comprehensive tutorial on using the Index feature in LlamaCloud to build powerful RAG and agentic applications over a knowledge base of documents.\n",
    "\n",
    "In this example we use Apple and Tesla 10-K filings from 2019-2023. We show you how to use the `LlamaCloudIndex` class from `llama_cloud_services` for retrieval.\n",
    "\n",
    "## Structure\n",
    "\n",
    "**🚀 Getting Started with the Basics** \n",
    "Learn the fundamentals of LlamaCloudIndex:\n",
    "1. **Index Creation**: Setting up a LlamaCloudIndex with 10 documents (5 Apple + 5 Tesla 10-Ks)\n",
    "2. **Chunk Retrieval**: Standard retrieval for specific information\n",
    "3. **Simple Query Engine**: Building basic RAG without complexity\n",
    "4. **Basic Agent**: Simple agent with conversational capability\n",
    "\n",
    "**🎯 Advanced Features**\n",
    "Explore more sophisticated patterns:\n",
    "1. **File-Level Retrieval**: Retrieving entire documents for comprehensive analysis\n",
    "2. **Smart Agent**: Agent that can choose between chunk and file retrieval\n",
    "3. **Query Engine with Citations**: Enhanced RAG with source citations\n",
    "\n",
    "**Status:**\n",
    "| Last Updated | Version | State      |\n",
    "|--------------|---------|------------|\n",
    "| Sep-02-2025  | 0.6.62  | Active     |\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup and Installation\n",
    "\n",
    "First, let's install the required packages and set up our environment.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Install required packages\n",
    "%pip install \"llama-index>=0.13.0<0.14.0\" llama-cloud-services\n",
    "%pip install llama-index-llms-openai llama-index-embeddings-openai"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## API Keys Setup\n",
    "\n",
    "Set your API keys. You'll need:\n",
    "- **LlamaCloud API Key**: Get from [cloud.llamaindex.ai](https://cloud.llamaindex.ai)\n",
    "- **OpenAI API Key**: For LLM and embedding models\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "\n",
    "# Set your API keys\n",
    "os.environ[\"LLAMA_CLOUD_API_KEY\"] = \"llx-...\"\n",
    "os.environ[\"OPENAI_API_KEY\"] = \"sk-...\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Data Download\n",
    "\n",
    "Let's download the Apple and Tesla 10-K filings for 2019-2023. These are publicly available SEC filings that provide comprehensive annual business information.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Download Apple 10-K filings (2019-2023)\n",
    "print(\"Downloading Apple 10-K filings...\")\n",
    "!wget \"https://s2.q4cdn.com/470004039/files/doc_earnings/2023/q4/filing/_10-K-Q4-2023-As-Filed.pdf\" -O data/apple_2023.pdf\n",
    "!wget \"https://s2.q4cdn.com/470004039/files/doc_financials/2022/q4/_10-K-2022-(As-Filed).pdf\" -O data/apple_2022.pdf\n",
    "!wget \"https://s2.q4cdn.com/470004039/files/doc_financials/2021/q4/_10-K-2021-(As-Filed).pdf\" -O data/apple_2021.pdf\n",
    "!wget \"https://s2.q4cdn.com/470004039/files/doc_financials/2020/ar/_10-K-2020-(As-Filed).pdf\" -O data/apple_2020.pdf\n",
    "!wget \"https://www.dropbox.com/scl/fi/i6vk884ggtq382mu3whfz/apple_2019_10k.pdf?rlkey=eudxh3muxh7kop43ov4bgaj5i&dl=1\" -O data/apple_2019.pdf\n",
    "\n",
    "print(\"Downloading Tesla 10-K filings...\")\n",
    "# Download Tesla 10-K filings (2019-2023)\n",
    "!wget \"https://ir.tesla.com/_flysystem/s3/sec/000162828024002390/tsla-20231231-gen.pdf\" -O data/tesla_2023.pdf\n",
    "!wget \"https://ir.tesla.com/_flysystem/s3/sec/000095017023001409/tsla-20221231-gen.pdf\" -O data/tesla_2022.pdf\n",
    "!wget \"https://www.dropbox.com/scl/fi/ptk83fmye7lqr7pz9r6dm/tesla_2021_10k.pdf?rlkey=24kxixeajbw9nru1sd6tg3bye&dl=1\" -O data/tesla_2021.pdf\n",
    "!wget \"https://ir.tesla.com/_flysystem/s3/sec/000156459021004599/tsla-10k_20201231-gen.pdf\" -O data/tesla_2020.pdf\n",
    "!wget \"https://ir.tesla.com/_flysystem/s3/sec/000156459020004475/tsla-10k_20191231-gen_0.pdf\" -O data/tesla_2019.pdf\n",
    "\n",
    "print(\"\\nDownload complete! Files available:\")\n",
    "!ls -la data/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Creating a LlamaCloudIndex\n",
    "\n",
    "Now we'll create a LlamaCloudIndex by uploading our documents. LlamaCloudIndex provides a managed indexing solution that handles:\n",
    "- Document parsing and chunking\n",
    "- Embedding generation\n",
    "- Hybrid search (dense + sparse)\n",
    "- Advanced retrieval with reranking"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from llama_cloud_services import LlamaCloudIndex\n",
    "\n",
    "# create an empty index\n",
    "index = await LlamaCloudIndex.acreate_index(\n",
    "    name=\"apple_tesla_10k\",\n",
    "    project_name=\"Default\",\n",
    "    organization_id=\"43b88c8f-e488-46f6-9013-698e3d2e374a\",\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Index ID: 250a1689-712e-4698-8b5d-9c973cb05ef1\n"
     ]
    }
   ],
   "source": [
    "print(f\"Index ID: {index.id}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now with our empty index, we can upload our documents."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uploaded 10 files. Waiting for completion... (this may take a few minutes)\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "ManagedIngestionStatusResponse(job_id=None, deployment_date=None, status=<ManagedIngestionStatus.SUCCESS: 'SUCCESS'>, error=None, effective_at=datetime.datetime(2025, 9, 2, 20, 3, 31, 983235))"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "paths = os.listdir(\"data\")\n",
    "\n",
    "file_ids = []\n",
    "for path in paths:\n",
    "    file_ids.append(\n",
    "        await index.aupload_file(os.path.join(\"./data\", path), wait_for_ingestion=False)\n",
    "    )\n",
    "\n",
    "print(\n",
    "    f\"Uploaded {len(file_ids)} files. Waiting for completion... (this may take a few minutes)\"\n",
    ")\n",
    "await index.await_for_completion(file_ids=file_ids)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 🚀 Getting Started with the Basics\n",
    "\n",
    "Now that we have our index, let's explore the fundamental patterns for building RAG applications.\n",
    "\n",
    "### Chunk-Level Retrieval\n",
    "\n",
    "Let's start with the most common retrieval pattern - finding relevant chunks of text from our documents.\n",
    "The chunk-level retriever performs hybrid search (dense + sparse) with reranking to find the most relevant pieces of information.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Retrieved 3 chunks for query: 'What are the main revenue sources for Apple in 2023?'\n",
      "\n",
      "**Chunk 1** (Score: 0.875)\n",
      "Source: apple_2023.pdf\n",
      "Content: Apple Inc. | 2023 Form 10-K | 35\n",
      "\n",
      "Net sales disaggregated by significant products and services for 2023, 2022 and 2021 were as follows (in millions):\n",
      "\n",
      "|                                     | 2023      | 2022      | 2021      |\n",
      "| ----------------------------------- | --------- | --------- | ---------...\n",
      "\n",
      "**Chunk 2** (Score: 0.777)\n",
      "Source: apple_2023.pdf\n",
      "Content: Services\n",
      "\n",
      "# Advertising\n",
      "\n",
      "The Company’s advertising services include third-party licensing arrangements and the Company’s own advertising platforms.\n",
      "\n",
      "# AppleCare\n",
      "\n",
      "The Company offers a portfolio of fee-based service and support products under the AppleCare® brand. The offerings provide priority access...\n",
      "\n",
      "**Chunk 3** (Score: 0.769)\n",
      "Source: apple_2023.pdf\n",
      "Content: Apple Inc.\n",
      "# Notes to Consolidated Financial Statements\n",
      "\n",
      "# Note 1 – Summary of Significant Accounting Policies\n",
      "\n",
      "# Basis of Presentation and Preparation\n",
      "\n",
      "The consolidated financial statements include the accounts of Apple Inc. and its wholly owned subsidiaries. The preparation of these consolidated f...\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Create a chunk-level retriever\n",
    "chunk_retriever = index.as_retriever(\n",
    "    dense_similarity_top_k=5,\n",
    "    sparse_similarity_top_k=5,\n",
    "    enable_reranking=True,\n",
    "    rerank_top_n=3,\n",
    ")\n",
    "\n",
    "# Example query\n",
    "query = \"What are the main revenue sources for Apple in 2023?\"\n",
    "chunk_nodes = await chunk_retriever.aretrieve(query)\n",
    "\n",
    "print(f\"Retrieved {len(chunk_nodes)} chunks for query: '{query}'\\n\")\n",
    "\n",
    "for i, node in enumerate(chunk_nodes):\n",
    "    print(f\"**Chunk {i+1}** (Score: {node.score:.3f})\")\n",
    "    print(f\"Source: {node.metadata.get('file_name', 'Unknown')}\")\n",
    "    print(f\"Content: {node.text[:300]}...\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Simple Query Engine\n",
    "\n",
    "Now let's build a basic RAG query engine that combines retrieval with response generation.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "🤖 **Simple RAG Query Engine Created**\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from llama_index.core.query_engine import RetrieverQueryEngine\n",
    "from llama_index.llms.openai import OpenAI\n",
    "\n",
    "# Set up LLM\n",
    "llm = OpenAI(model=\"gpt-5-mini\")\n",
    "\n",
    "# Create a simple query engine\n",
    "query_engine = RetrieverQueryEngine.from_args(\n",
    "    chunk_retriever, llm=llm, response_mode=\"compact\"\n",
    ")\n",
    "\n",
    "print(\"🤖 **Simple RAG Query Engine Created**\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's test our query engine with some basic questions about Apple and Tesla:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "**Q: What was Apple's total revenue in 2023?**\n",
      "**A:** Apple's total revenue (net sales) in 2023 was $383.3 billion (approximately $383,285 million).\n",
      "\n",
      "**Top source:**\n",
      "{'id': 'apple_2023.pdf', 'file_size': 714094, 'last_modified_at': '2025-09-02T19:59:21', 'file_path': 'apple_2023.pdf', 'file_name': 'apple_2023.pdf', 'external_file_id': 'apple_2023.pdf', 'file_id': '960f2aa6-4113-41b3-9ff6-1a66ee83b84a', 'pipeline_file_id': '04eee09b-2cca-482d-8540-34ad5151e24d', 'pipeline_id': '250a1689-712e-4698-8b5d-9c973cb05ef1', 'page_label': 23, 'start_page_index': 22, 'start_page_label': 23, 'end_page_index': 22, 'end_page_label': 23, 'document_id': 'efc64ba579b1f5b4a28c92a110591bdbb6b33843fab096f5d8', 'start_char_idx': 206312, 'end_char_idx': 209383}\n",
      "\n",
      "**Top source:**\n",
      "{'id': 'apple_2023.pdf', 'file_size': 714094, 'last_modified_at': '2025-09-02T19:59:21', 'file_path': 'apple_2023.pdf', 'file_name': 'apple_2023.pdf', 'external_file_id': 'apple_2023.pdf', 'file_id': '960f2aa6-4113-41b3-9ff6-1a66ee83b84a', 'pipeline_file_id': '04eee09b-2cca-482d-8540-34ad5151e24d', 'pipeline_id': '250a1689-712e-4698-8b5d-9c973cb05ef1', 'page_label': 38, 'start_page_index': 37, 'start_page_label': 38, 'end_page_index': 37, 'end_page_label': 38, 'document_id': 'efc64ba579b1f5b4a28c92a110591bdbb6b33843fab096f5d8', 'start_char_idx': 309858, 'end_char_idx': 313198}\n",
      "\n",
      "**Top source:**\n",
      "{'id': 'apple_2023.pdf', 'file_size': 714094, 'last_modified_at': '2025-09-02T19:59:21', 'file_path': 'apple_2023.pdf', 'file_name': 'apple_2023.pdf', 'external_file_id': 'apple_2023.pdf', 'file_id': '960f2aa6-4113-41b3-9ff6-1a66ee83b84a', 'pipeline_file_id': '04eee09b-2cca-482d-8540-34ad5151e24d', 'pipeline_id': '250a1689-712e-4698-8b5d-9c973cb05ef1', 'page_label': 51, 'start_page_index': 50, 'start_page_label': 51, 'end_page_index': 50, 'end_page_label': 51, 'document_id': 'efc64ba579b1f5b4a28c92a110591bdbb6b33843fab096f5d8', 'start_char_idx': 415931, 'end_char_idx': 416939}\n",
      "\n",
      "------------------------------------------------------------\n",
      "\n",
      "**Q: What are Tesla's main products?**\n",
      "**A:** Tesla’s main products fall into two broad categories:\n",
      "\n",
      "- Automotive products\n",
      "  - Fully electric vehicles: Model 3, Model Y, Model S, Model X, Cybertruck\n",
      "  - Commercial vehicle: Tesla Semi\n",
      "  - Related offerings: vehicle sales and leasing, used vehicles, after‑sales service, body shops, vehicle insurance, paid Supercharging\n",
      "\n",
      "- Energy generation and storage products\n",
      "  - Home and commercial battery systems: Powerwall, Megapack (and earlier Powerpack generations)\n",
      "  - Solar offerings: retrofit solar systems and the Solar Roof\n",
      "  - Related software and services for system control, dispatch and optimization\n",
      "\n",
      "- Supporting infrastructure and technology\n",
      "  - Charging network (Superchargers, Destination Chargers), service centers, Mobile Service\n",
      "  - Full Self‑Driving software and other vehicle/energy software platforms\n",
      "\n",
      "**Top source:**\n",
      "{'id': 'tesla_2023.pdf', 'file_size': 984581, 'last_modified_at': '2025-09-02T19:59:17', 'file_path': 'tesla_2023.pdf', 'file_name': 'tesla_2023.pdf', 'external_file_id': 'tesla_2023.pdf', 'file_id': '51d46ff4-b9b8-49df-baff-8560144c932d', 'pipeline_file_id': 'f690884c-b126-4fc6-9d83-5933a649fe75', 'pipeline_id': '250a1689-712e-4698-8b5d-9c973cb05ef1', 'page_label': 5, 'start_page_index': 4, 'start_page_label': 5, 'end_page_index': 4, 'end_page_label': 5, 'document_id': 'ab35f7e53222722a64320420221bdd7321a0567dd9ca612aa1', 'start_char_idx': 19950, 'end_char_idx': 23884}\n",
      "\n",
      "**Top source:**\n",
      "{'id': 'tesla_2022.pdf', 'file_size': 1650825, 'last_modified_at': '2025-09-02T19:59:20', 'file_path': 'tesla_2022.pdf', 'file_name': 'tesla_2022.pdf', 'external_file_id': 'tesla_2022.pdf', 'file_id': 'ef9fbd09-f1c0-46f4-8430-21e697aad9cd', 'pipeline_file_id': '2401877f-fae2-45f9-a624-32db85120cab', 'pipeline_id': '250a1689-712e-4698-8b5d-9c973cb05ef1', 'page_label': 4, 'start_page_index': 3, 'start_page_label': 4, 'end_page_index': 3, 'end_page_label': 4, 'document_id': '1c7a8ca35f9d58cac21a0c7100934f82441dcd38f5e4c8249e', 'start_char_idx': 18539, 'end_char_idx': 22906}\n",
      "\n",
      "**Top source:**\n",
      "{'id': 'tesla_2020.pdf', 'file_size': 2659773, 'last_modified_at': '2025-09-02T19:59:13', 'file_path': 'tesla_2020.pdf', 'file_name': 'tesla_2020.pdf', 'external_file_id': 'tesla_2020.pdf', 'file_id': '36960c83-248e-4dde-abf5-297c6fa2dc67', 'pipeline_file_id': '8f3bfe73-d5b7-463c-8fb7-2fd1f2b921a1', 'pipeline_id': '250a1689-712e-4698-8b5d-9c973cb05ef1', 'page_label': 4, 'start_page_index': 3, 'start_page_label': 4, 'end_page_index': 3, 'end_page_label': 4, 'document_id': 'a4a6744adb65432542c85257fa45a43e557adfc221ab6e3d85', 'start_char_idx': 18067, 'end_char_idx': 22210}\n",
      "\n",
      "------------------------------------------------------------\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Test with simple questions\n",
    "basic_queries = [\n",
    "    \"What was Apple's total revenue in 2023?\",\n",
    "    \"What are Tesla's main products?\",\n",
    "]\n",
    "\n",
    "for query in basic_queries:\n",
    "    print(f\"**Q: {query}**\")\n",
    "    response = await query_engine.aquery(query)\n",
    "    print(f\"**A:** {response}\\n\")\n",
    "    for source in response.source_nodes:\n",
    "        print(\n",
    "            f\"\"\"**Top source:**\n",
    "{source.node.metadata}\n",
    "\"\"\"\n",
    "        )\n",
    "    print(\"-\" * 60 + \"\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Basic Agent\n",
    "\n",
    "Let's create a simple agent that can have conversations and maintain memory while answering questions about our documents.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "🤖 **Basic Agent Ready!**\n",
      "The agent can answer questions about both Apple and Tesla using FunctionAgent.\n"
     ]
    }
   ],
   "source": [
    "from llama_index.core.tools import QueryEngineTool\n",
    "from llama_index.core.agent.workflow import FunctionAgent\n",
    "from llama_index.core.memory import Memory\n",
    "\n",
    "# Create a tool for the agent - single tool for both companies\n",
    "document_tool = QueryEngineTool.from_defaults(\n",
    "    query_engine=query_engine,\n",
    "    name=\"document_search\",\n",
    "    description=\"Search and analyze Apple and Tesla 10-K filings (2019-2023). Use for questions about either company's business, financials, products, or strategy.\",\n",
    ")\n",
    "\n",
    "# Create the agent using FunctionAgent with memory\n",
    "memory = Memory.from_defaults(token_limit=40000, token_flush_size=2000)\n",
    "agent = FunctionAgent(\n",
    "    tools=[document_tool],\n",
    "    llm=llm,\n",
    "    system_prompt=\"You are a helpful assistant that can search and analyze financial documents from Apple and Tesla. Use the available tools to answer questions accurately.\",\n",
    ")\n",
    "\n",
    "print(\"🤖 **Basic Agent Ready!**\")\n",
    "print(\"The agent can answer questions about both Apple and Tesla using FunctionAgent.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's test the agent with a conversational flow where it remembers previous questions:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "💬 **Agent Conversation**\n",
      "\n",
      "**Turn 1: What was Apple's revenue in 2023?**\n",
      "**Agent:** Apple’s revenue (total net sales) for fiscal 2023 was $383,285 million — about $383.3 billion (per Apple’s 2023 Form 10-K).  \n",
      "\n",
      "Do you want a breakdown by product category or region?\n",
      "\n",
      "------------------------------------------------------------\n",
      "\n",
      "**Turn 2: How does that compare to Tesla's revenue?**\n",
      "**Agent:** Tesla’s total revenue for 2023 was $96,773 million (about $96.8 billion).\n",
      "\n",
      "Comparison:\n",
      "- Apple (fiscal 2023): $383,285 million (~$383.3B)  \n",
      "- Tesla (calendar 2023): $96,773 million (~$96.8B)\n",
      "\n",
      "- Apple’s revenue was about 3.96× Tesla’s (Apple ≈ $286.5B more).  \n",
      "- Put another way, Tesla’s 2023 revenue was ≈25.3% of Apple’s, and Apple’s revenue was ≈296% higher than Tesla’s.\n",
      "\n",
      "Note: Apple reports a fiscal year ending Sept 30, 2023; Tesla’s is calendar year ending Dec 31, 2023. Want a year‑over‑year growth comparison or breakdown by product/segment?\n",
      "\n",
      "------------------------------------------------------------\n",
      "\n",
      "**Turn 3: What do you think is the main reason for the difference?**\n",
      "**Agent:** Short answer: it’s mainly due to scale and business model differences — Apple sells vastly more units across multiple mature product lines (especially the iPhone) plus a large, fast‑growing services business, while Tesla’s revenue is concentrated in vehicle sales (lower unit volumes today) with smaller contributions from energy and services.\n",
      "\n",
      "Key points:\n",
      "- Product scale and volume: Apple’s flagship iPhone has a huge global installed base and frequent upgrade cycle, generating very large annual hardware sales. Tesla sells far fewer vehicles by unit count in 2023 than Apple sells iPhones and other devices.\n",
      "- Diversification and recurring revenue: Apple has multiple major hardware lines (iPhone, Mac, iPad, wearables) plus a large services business (App Store, iCloud, Apple Music, etc.) that adds recurring, high‑margin revenue. Tesla’s core business is auto sales; energy/storage and software/services are much smaller today.\n",
      "- Price × volume dynamics: Apple’s ecosystem drives high average revenue per customer (device sales plus services, accessories, and repeat purchases). Tesla’s average transaction is high (a car) but overall unit volume is far lower than consumer electronics.\n",
      "- Market maturity and adoption: Smartphones and related services are a fully mature, massive market; EVs are still a smaller (though fast‑growing) share of the global vehicle market, limiting current revenue scale.\n",
      "- Distribution and channel: Apple has an extensive global retail and channel network and an enormous installed base that supports ongoing accessory and service sales.\n",
      "\n",
      "If you want, I can:\n",
      "- Break down Apple’s 2023 revenue by product and services, or\n",
      "- Compare unit volumes (iPhones vs Tesla vehicle deliveries) and attach rates to show the scale gap. Which would you prefer?\n",
      "\n",
      "------------------------------------------------------------\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Example conversation showing the agent capabilities\n",
    "conversation = [\n",
    "    \"What was Apple's revenue in 2023?\",\n",
    "    \"How does that compare to Tesla's revenue?\",\n",
    "    \"What do you think is the main reason for the difference?\",\n",
    "]\n",
    "\n",
    "print(\"💬 **Agent Conversation**\\n\")\n",
    "\n",
    "\n",
    "async def run_conversation():\n",
    "    for i, query in enumerate(conversation, 1):\n",
    "        print(f\"**Turn {i}: {query}**\")\n",
    "        response = await agent.run(query, memory=memory)\n",
    "        print(f\"**Agent:** {response}\\n\")\n",
    "        print(\"-\" * 60 + \"\\n\")\n",
    "\n",
    "\n",
    "# Run the conversation\n",
    "await run_conversation()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 🎯 Advanced Features\n",
    "\n",
    "Now let's explore more sophisticated patterns that showcase the full power of LlamaCloudIndex.\n",
    "\n",
    "### File-Level Retrieval\n",
    "\n",
    "For questions requiring comprehensive document context, file-level retrieval returns entire documents rather than just chunks.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Retrieved 1 documents for query: 'Give me a comprehensive analysis of Tesla's financials in 2023.'\n",
      "\n",
      "**Document 1**\n",
      "Source: tesla_2023.pdf\n",
      "Content length: 536,235 characters\n",
      "First 300 chars: \n",
      "UNITED STATES SECURITIES AND EXCHANGE COMMISSION\n",
      "Washington, D.C. 20549 FORM 10-K\n",
      "\n",
      "# FORM 10-K\n",
      "\n",
      "(Mark One)\n",
      "\n",
      "x ANNUAL REPORT PURSUANT TO SECTION 13 OR 15(d) OF THE SECURITIES EXCHANGE ACT OF 1934\n",
      "\n",
      "For the fiscal year ended December 31, 2023\n",
      "\n",
      "OR\n",
      "\n",
      "o TRANSITION REPORT PURSUANT TO SECTION 13 OR 15(d) OF...\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Create a file-level retriever\n",
    "file_retriever = index.as_retriever(\n",
    "    retrieval_mode=\"files_via_content\", files_top_k=1  # or \"files_via_metadata\"\n",
    ")\n",
    "\n",
    "# Example query that benefits from full document context\n",
    "query = \"Give me a comprehensive analysis of Tesla's financials in 2023.\"\n",
    "file_nodes = await file_retriever.aretrieve(query)\n",
    "\n",
    "print(f\"Retrieved {len(file_nodes)} documents for query: '{query}'\\n\")\n",
    "\n",
    "for i, node in enumerate(file_nodes):\n",
    "    print(f\"**Document {i+1}**\")\n",
    "    print(f\"Source: {node.metadata.get('file_name', 'Unknown')}\")\n",
    "    print(f\"Content length: {len(node.text):,} characters\")\n",
    "    print(f\"First 300 chars: {node.text[:300]}...\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Smart Agent with Multiple Retrieval Strategies\n",
    "\n",
    "Let's create an advanced agent that can choose between chunk-level and file-level retrieval based on the question type.\n",
    "\n",
    "This agent will have two tools - one for specific factual queries (chunk-level) and one for comprehensive analysis (file-level).\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "🧠 **Smart Agent Ready!**\n",
      "The agent can choose between:\n",
      "  - Specific search (chunk-level) for targeted queries\n",
      "  - Comprehensive analysis (file-level) for complex questions\n"
     ]
    }
   ],
   "source": [
    "fast_llm = OpenAI(model=\"gpt-4o-mini\", temperature=0.1)\n",
    "\n",
    "# Create query engines for both retrieval strategies\n",
    "chunk_query_engine = RetrieverQueryEngine.from_args(\n",
    "    chunk_retriever, llm=fast_llm, response_mode=\"compact\"\n",
    ")\n",
    "\n",
    "file_query_engine = RetrieverQueryEngine.from_args(\n",
    "    file_retriever,\n",
    "    llm=fast_llm,\n",
    "    response_mode=\"tree_summarize\",  # Better for large documents\n",
    ")\n",
    "\n",
    "# Create tools for the smart agent\n",
    "smart_tools = [\n",
    "    QueryEngineTool.from_defaults(\n",
    "        query_engine=chunk_query_engine,\n",
    "        name=\"specific_search\",\n",
    "        description=\"Search for specific facts, numbers, or targeted information from Apple and Tesla 10-K filings. Best for precise factual queries.\",\n",
    "    ),\n",
    "    QueryEngineTool.from_defaults(\n",
    "        query_engine=file_query_engine,\n",
    "        name=\"comprehensive_analysis\",\n",
    "        description=\"Perform comprehensive document-level analysis requiring full context. Use for complex questions, comparisons, or broad business analysis.\",\n",
    "    ),\n",
    "]\n",
    "\n",
    "# Create the smart agent using FunctionAgent\n",
    "smart_agent = FunctionAgent(\n",
    "    tools=smart_tools,\n",
    "    llm=llm,\n",
    "    system_prompt=\"You are an intelligent assistant with access to two search strategies. Use 'specific_search' for targeted factual queries and 'comprehensive_analysis' for complex analysis requiring full document context. Choose the appropriate tool based on the question type.\",\n",
    ")\n",
    "\n",
    "print(\"🧠 **Smart Agent Ready!**\")\n",
    "print(\"The agent can choose between:\")\n",
    "print(\"  - Specific search (chunk-level) for targeted queries\")\n",
    "print(\"  - Comprehensive analysis (file-level) for complex questions\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's test queries that should trigger different retrieval strategies:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "🧠 **Smart Agent Tool Selection Test**\n",
      "\n",
      "**Query 1: What was Apple's exact revenue in 2023?**\n",
      "Call specific_search with args {'input': 'Apple 2023 total revenue exact amount (from Apple 10-K or Form 10-K for fiscal year 2023)'}\n",
      "Returned: The total revenue for Apple in fiscal year 2023 was $383.3 billion.\n",
      "Call specific_search with args {'input': 'Exact total net sales reported by Apple in fiscal year 2023 in its 2023 Form 10-K (full figure in dollars)'}\n",
      "Returned: $383,285,000,000\n",
      "Apple's total net sales (fiscal year 2023, year ended Sept. 30, 2023) were $383,285,000,000 (about $383.3 billion), per Apple’s 2023 Form 10-K.\n",
      "================================================================================\n",
      "\n",
      "**Query 2: Analyze Tesla's overall business transformation from 2022 to 2023**\n",
      "Call comprehensive_analysis with args {'input': \"Analyze Tesla's overall business transformation from 2022 to 2023 using Tesla's 2023 Form 10-K and relevant figures: changes in revenue, gross margin, operating income, net income, vehicle production and deliveries, energy and storage, services and other, geographic revenue shifts, capital expenditures, cash flow, unit economics, pricing changes, cost reductions, manufacturing capacity expansion (Giga Berlin, Giga Texas), regulatory credits, FSD/software revenue, and any strategic shifts announced or evident in 2023 vs 2022. Provide quantitative comparisons where possible and summarize key drivers, risks, and outlook implications.\"}\n",
      "Returned: In analyzing Tesla's overall business transformation from 2022 to 2023, several key metrics and strategic shifts highlight the company's evolution during this period. \n",
      "\n",
      "### Revenue Changes\n",
      "Tesla's total revenues increased significantly from $81.46 billion in 2022 to $96.77 billion in 2023, marking a growth of approximately 19%. This growth was driven primarily by the automotive segment, which saw revenues rise from $71.46 billion to $82.42 billion, an increase of 15%. The energy generation and storage segment also contributed, with revenues growing from $3.91 billion to $6.04 billion, a substantial increase of 54%. Services and other revenue rose from $6.09 billion to $8.32 billion, reflecting a 37% increase.\n",
      "\n",
      "### Gross Margin and Operating Income\n",
      "The overall gross margin decreased from 25.6% in 2022 to 18.2% in 2023. This decline was primarily attributed to a lower average selling price of vehicles, which was influenced by price reductions implemented to stimulate demand. Operating income fell from $13.66 billion in 2022 to $8.89 billion in 2023, indicating a significant drop in profitability, largely due to increased costs associated with production and a shift in sales mix.\n",
      "\n",
      "### Net Income\n",
      "Net income attributable to common stockholders increased from $12.56 billion in 2022 to $15.00 billion in 2023, benefiting from a one-time non-cash tax benefit of $5.93 billion related to the release of a valuation allowance on deferred tax assets. This resulted in a notable effective tax rate change from an expense of 8% in 2022 to a benefit of 50% in 2023.\n",
      "\n",
      "### Vehicle Production and Deliveries\n",
      "In 2023, Tesla produced 1,845,985 vehicles and delivered 1,808,581, compared to 1,313,851 vehicles produced and 1,313,851 delivered in 2022. This represents a production increase of approximately 40% year-over-year, showcasing Tesla's ramp-up in manufacturing capacity, particularly at Gigafactory Berlin and Gigafactory Texas.\n",
      "\n",
      "### Energy and Storage\n",
      "Tesla deployed 14.72 GWh of energy storage products in 2023, up from previous years, and installed 223 megawatts of solar energy systems, indicating a focus on expanding its energy generation and storage capabilities.\n",
      "\n",
      "### Services and Other\n",
      "The services and other segment, which includes used vehicle sales and non-warranty after-sales services, saw significant growth, reflecting the increasing size of Tesla's vehicle fleet and the associated service needs.\n",
      "\n",
      "### Geographic Revenue Shifts\n",
      "Geographically, Tesla's revenue from the United States increased to $45.24 billion in 2023 from $40.55 billion in 2022. Revenue from China also rose to $21.75 billion from $18.15 billion, while other international markets contributed $29.79 billion, up from $22.76 billion. This indicates a broadening of Tesla's market presence and a successful strategy to penetrate international markets.\n",
      "\n",
      "### Capital Expenditures and Cash Flow\n",
      "Capital expenditures rose from $7.16 billion in 2022 to $8.90 billion in 2023, reflecting ongoing investments in manufacturing capacity and infrastructure. Cash flow from operating activities decreased slightly from $14.72 billion in 2022 to $13.26 billion in 2023, primarily due to changes in net income and working capital management.\n",
      "\n",
      "### Unit Economics and Pricing Changes\n",
      "Tesla's pricing strategy involved significant reductions in vehicle prices to stimulate demand, which contributed to the decrease in gross margin. The average selling price of vehicles fell, impacting revenue per unit but potentially increasing overall sales volume.\n",
      "\n",
      "### Cost Reductions and Manufacturing Capacity Expansion\n",
      "Tesla's focus on cost reductions was evident in its efforts to improve manufacturing efficiencies and reduce material costs. The expansion of Gigafactory Berlin and Gigafactory Texas played a crucial role in increasing production capacity and localizing supply chains, which are essential for meeting growing demand.\n",
      "\n",
      "### Regulatory Credits and FSD/Software Revenue\n",
      "Revenue from automotive regulatory credits remained relatively stable, increasing slightly from $1.78 billion to $1.79 billion. The development and deployment of Full Self-Driving (FSD) capabilities and software features continue to be a strategic focus, with ongoing enhancements expected to drive future revenue growth.\n",
      "\n",
      "### Strategic Shifts\n",
      "In 2023, Tesla emphasized its commitment to vertical integration, localization of supply chains, and the development of new products, including the Cybertruck. The company also announced plans for an autonomous ride-hailing network, which could open new revenue streams.\n",
      "\n",
      "### Key Drivers, Risks, and Outlook Implications\n",
      "Key drivers of Tesla's transformation include increased production capacity, strategic pricing adjustments, and expansion into new markets. However, risks such as supply chain disruptions, regulatory challenges, and competition from other electric vehicle manufacturers remain significant. The outlook for Tesla appears positive, with expectations for continued growth in vehicle production and energy solutions, although maintaining profitability amidst pricing pressures will be crucial.\n",
      "\n",
      "In summary, Tesla's business transformation from 2022 to 2023 reflects a robust growth trajectory, marked by increased production, revenue growth across segments, and strategic investments in manufacturing and technology, despite challenges in maintaining margins and navigating a competitive landscape.\n",
      "Below is a concise, evidence-based analysis of Tesla’s business transformation from 2022 to 2023, using figures reported in Tesla’s 2023 Form 10‑K.\n",
      "\n",
      "High-level summary\n",
      "- Tesla scaled materially in 2023: revenue and volumes rose substantially, driven by factory ramps (primarily Giga Texas and Giga Berlin) and stronger energy/storage sales.  \n",
      "- Profitability mix shifted: lower automotive ASPs and price cuts compressed gross margins and operating income, but a large one‑time tax benefit boosted reported net income.  \n",
      "- Strategic emphasis moved toward volume expansion, energy/storage growth, services/recurring revenue, and continued investment in autonomy/software monetization — all while managing margin pressure and rising capex.\n",
      "\n",
      "Key numbers (2022 → 2023)\n",
      "- Total revenue: $81.46B → $96.77B (+≈19%).  \n",
      "  - Automotive revenue: $71.46B → $82.42B (+≈15%).  \n",
      "  - Energy generation & storage: $3.91B → $6.04B (+≈54%).  \n",
      "  - Services & other: $6.09B → $8.32B (+≈37%).  \n",
      "- Gross margin (company-wide): 25.6% → 18.2% (decline of ~7.4 percentage points).  \n",
      "- Operating income: $13.66B → $8.89B (≈-35%).  \n",
      "- Net income attributable to common stockholders: $12.56B → $15.00B (+≈19%). Note: 2023 included a significant one‑time non‑cash tax benefit (release of valuation allowance) that materially increased net income and produced an effective tax benefit.  \n",
      "- Vehicle production & deliveries: production and deliveries rose ~40% year‑over‑year (2023 production ~1.846M; deliveries ~1.809M), reflecting the ramp at new giga factories.  \n",
      "- Energy deployments: storage deployments and solar installations increased (e.g., storage GWh deployed rose notably; solar MW installed also grew).  \n",
      "- Capital expenditures: $7.16B → $8.90B (+≈24%), reflecting factory buildouts and capacity expansion.  \n",
      "- Cash flow from operations: $14.72B → $13.26B (≈-9.9%), reflecting margin pressure and working capital changes.  \n",
      "- Automotive regulatory credits: ~$1.78B → ~$1.79B (roughly flat).\n",
      "\n",
      "Drivers of the transformation\n",
      "- Capacity expansion and localization: Full ramps at Giga Texas and Giga Berlin materially increased global production capacity and localized supply chains, enabling much higher volumes.  \n",
      "- Pricing strategy: Aggressive price reductions on multiple models in 2023 stimulated demand/volume but reduced ASPs and margins.  \n",
      "- Mix shift and cost dynamics: Higher mix of lower‑price variants and cost inflation on certain inputs pressured automotive gross margins. Ongoing efficiency efforts continue but were not enough to offset ASP declines in 2023.  \n",
      "- Energy & services growth: Strong growth in energy storage deployments and expanding services/used-vehicle revenues diversified revenue beyond new-car sales.  \n",
      "- Software/FSD progress: Continued development and monetization attempts for Full Self-Driving / software features remain strategic for higher-margin recurring revenue, though material FSD revenue scale remains limited in 2023 relative to automotive sales.  \n",
      "- One‑time tax benefit: The release of valuation allowance on deferred tax assets created a large non-operational boost to net income and tax rate.\n",
      "\n",
      "Risks and headwinds observed in 2023\n",
      "- Margin sustainability: Lower ASPs and competitive pricing put significant pressure on gross margins and operating income; restoring margin requires cost improvements, better mix, or higher priced feature monetization.  \n",
      "- Competition and pricing pressure: Intensifying EV competition globally may force continued price actions.  \n",
      "- Execution risk on new products: Delivering new products (e.g., Cybertruck) and ramping new lines without cost overruns is critical.  \n",
      "- Regulatory and macro risks: Subsidy/regulatory changes (EV incentives), interest-rate sensitivity for auto purchases, and supply chain disruptions remain risks.  \n",
      "- Reliance on one-time items: 2023 net income improvement was materially aided by a one-time tax benefit; operational profitability was weaker.\n",
      "\n",
      "Implications for outlook\n",
      "- Volume-led growth likely continues as giga factories further optimize — revenue growth should persist given production capacity and global demand.  \n",
      "- Profitability trajectory depends on: (a) ability to recoup margins via cost reductions and efficiency at scale, (b) success in monetizing software/FSD and services as higher-margin revenue pools, and (c) avoiding sustained price-driven margin compression.  \n",
      "- Energy/storage and services represent meaningful diversification and long-term upside if deployment scale and margins improve.  \n",
      "- Capital intensity remains material while Tesla expands capacity and production tooling; disciplined capex and working-capital management will be important to sustain free cash flow.\n",
      "\n",
      "Bottom line\n",
      "From 2022 to 2023 Tesla moved from a phase of constraining supply to one of aggressive volume scale—growing revenue and deliveries substantially—but at the cost of compressed margins due to price cuts and mix shifts. The company is investing to lock in scale advantages (new gigafactories, tooling, energy business), while strategic priorities (autonomy, software monetization, energy/storage) aim to improve long‑term unit economics and recurring revenue. Near term the challenge is translating higher volume and diversification into sustained operating margin expansion without relying on one‑time accounting benefits.\n",
      "\n",
      "If you’d like, I can:\n",
      "- Produce a one‑page table with the key 2022 vs 2023 numbers and percent changes; or  \n",
      "- Drill deeper into one area (FSD economics, energy storage unit economics, factory-specific ramp metrics for Giga Berlin/Giga Texas, or region-by-region revenue trends).\n",
      "================================================================================\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from llama_index.core.agent import ToolCall, ToolCallResult, AgentStream\n",
    "\n",
    "# Test different types of queries to see tool selection\n",
    "test_queries = [\n",
    "    \"What was Apple's exact revenue in 2023?\",  # Should use specific_search\n",
    "    \"Analyze Tesla's overall business transformation from 2022 to 2023\",  # Should use comprehensive_analysis\n",
    "]\n",
    "\n",
    "print(\"🧠 **Smart Agent Tool Selection Test**\\n\")\n",
    "\n",
    "\n",
    "async def run_smart_tests():\n",
    "    smart_memory = Memory.from_defaults(token_limit=40000, token_flush_size=2000)\n",
    "    for i, query in enumerate(test_queries, 1):\n",
    "        print(f\"**Query {i}: {query}**\")\n",
    "        handler = smart_agent.run(query, memory=smart_memory)\n",
    "        async for ev in handler.stream_events():\n",
    "            if isinstance(ev, ToolCall):\n",
    "                print(f\"Call {ev.tool_name} with args {ev.tool_kwargs}\")\n",
    "            if isinstance(ev, ToolCallResult):\n",
    "                print(f\"Returned: {ev.tool_output}\")\n",
    "            elif isinstance(ev, AgentStream):\n",
    "                print(ev.delta, end=\"\", flush=True)\n",
    "\n",
    "        response = await handler\n",
    "        # Response already printed in the stream\n",
    "        # print(f\"**Agent:** {response}\\n\")\n",
    "        print(\"\\n\" + \"=\" * 80 + \"\\n\")\n",
    "\n",
    "\n",
    "# Run the smart agent tests\n",
    "await run_smart_tests()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Query Engine with Citations\n",
    "\n",
    "For transparency and verification, let's create a query engine that provides inline citations linking back to source documents.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Define citation components\n",
    "from typing import List, Optional\n",
    "from llama_index.core import QueryBundle\n",
    "from llama_index.core.postprocessor.types import BaseNodePostprocessor\n",
    "from llama_index.core.schema import NodeWithScore\n",
    "\n",
    "\n",
    "class NodeCitationProcessor(BaseNodePostprocessor):\n",
    "    \"\"\"Add node_id to metadata for citation linking.\"\"\"\n",
    "\n",
    "    def _postprocess_nodes(\n",
    "        self,\n",
    "        nodes: List[NodeWithScore],\n",
    "        query_bundle: Optional[QueryBundle] = None,\n",
    "    ) -> List[NodeWithScore]:\n",
    "        for node_with_score in nodes:\n",
    "            node_with_score.node.metadata[\"node_id\"] = node_with_score.node.node_id\n",
    "        return nodes\n",
    "\n",
    "\n",
    "# Citation system prompt\n",
    "SYSTEM_CITATION_PROMPT = \"\"\"You are answering questions using information from a knowledge base.\n",
    "\n",
    "IMPORTANT: You must cite your sources by adding [cite:NODE_ID] after each fact or claim.\n",
    "\n",
    "The NODE_ID is the unique identifier found in each document chunk's metadata.\n",
    "\n",
    "Example:\n",
    "- If you reference information from node \"abc123\", write: [cite:abc123]\n",
    "- Multiple facts from the same source: \"Revenue was $100B [cite:abc123] and grew 15% [cite:abc123]\"\n",
    "- Different sources: \"Apple grew 10% [cite:node1] while Tesla grew 20% [cite:node2]\"\n",
    "\n",
    "Always cite every factual claim - this ensures transparency and allows readers to verify information.\"\"\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "📚 **Citations Query Engine Ready!**\n"
     ]
    }
   ],
   "source": [
    "# Create query engine with citations\n",
    "# Note: System prompt attached to the llm is only applied in query engines\n",
    "citation_llm = OpenAI(model=\"gpt-5-mini\", system_prompt=SYSTEM_CITATION_PROMPT)\n",
    "\n",
    "citation_query_engine = RetrieverQueryEngine.from_args(\n",
    "    chunk_retriever,\n",
    "    llm=citation_llm,\n",
    "    response_mode=\"tree_summarize\",\n",
    "    node_postprocessors=[NodeCitationProcessor()],\n",
    ")\n",
    "\n",
    "# Function to process citations and create readable links\n",
    "import re\n",
    "\n",
    "\n",
    "def process_citations_with_sources(response) -> str:\n",
    "    content = str(response)\n",
    "    source_nodes = response.source_nodes\n",
    "\n",
    "    # Create a lookup: citation_id -> file info\n",
    "    id_to_metadata = {str(node.id_): node.metadata for node in source_nodes}\n",
    "\n",
    "    # Track citation order and assign human-friendly numbers\n",
    "    citation_order = {}\n",
    "    citation_counter = 1\n",
    "\n",
    "    def replace(match):\n",
    "        nonlocal citation_counter\n",
    "        citation_id = match.group(1).strip()\n",
    "\n",
    "        if citation_id not in citation_order:\n",
    "            citation_order[citation_id] = citation_counter\n",
    "            citation_counter += 1\n",
    "        number = citation_order[citation_id]\n",
    "\n",
    "        return f\"({number})\"\n",
    "\n",
    "    # Replace citations with numbered references\n",
    "    # Support both old [citation:id]() and new [cite:id] formats\n",
    "    citation_regex_old = re.compile(r\"\\[citation:([^\\]]+)\\]\\(\\)\")\n",
    "    citation_regex_new = re.compile(r\"\\[cite:([^\\]]+)\\]\")\n",
    "    content = citation_regex_old.sub(replace, content)\n",
    "    content = citation_regex_new.sub(replace, content)\n",
    "\n",
    "    # Remove incomplete citation tags\n",
    "    incomplete_regex = re.compile(r\"\\[citation:[^\\]]*$\")\n",
    "    content = incomplete_regex.sub(\"\", content)\n",
    "\n",
    "    # Add references section if there are citations\n",
    "    if citation_order:\n",
    "        content += \"\\n\\n**References:**\\n\"\n",
    "        for citation_id, number in sorted(citation_order.items(), key=lambda x: x[1]):\n",
    "            metadata = id_to_metadata.get(citation_id, {})\n",
    "            file_name = metadata.get(\"file_name\", \"unknown\")\n",
    "            page_number = metadata.get(\"page_label\", \"unknown\")\n",
    "            content += f\"{number}. {file_name} (Page {page_number})\\n\"\n",
    "\n",
    "    return content\n",
    "\n",
    "\n",
    "print(\"📚 **Citations Query Engine Ready!**\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "📚 **Query Engine with Citations**\n",
      "\n",
      "**Q: How did Tesla's automotive sales perform in 2023?**\n",
      "**A:** Automotive sales revenue rose $11.30 billion (17%) in 2023 versus 2022 (1).  \n",
      "The increase was driven primarily by an additional 473,382 combined Model 3 and Model Y cash deliveries from the global ramp of Model Y (1).  \n",
      "This revenue growth was partially offset by a lower average selling price, sales mix effects, and a negative impact from a stronger U.S. dollar (1).  \n",
      "Cost of automotive sales rose $15.52 billion (31%) in 2023, largely in line with higher deliveries, though average combined cost per unit declined due to sales mix, lower inbound freight and material costs, better fixed cost absorption, and IRA manufacturing credits (2).  \n",
      "As a result, total automotive gross margin fell from 28.5% to 19.4% year-over-year, primarily because of the lower average selling price partially offset by the favorable change in cost per unit and IRA credits (2).  \n",
      "Separately, automotive leasing revenue declined $356 million (14%) while services and other automotive revenue grew $2.23 billion (37%) in 2023 (3).\n",
      "\n",
      "**References:**\n",
      "1. tesla_2023.pdf (Page 39)\n",
      "2. tesla_2023.pdf (Page 41)\n",
      "3. tesla_2023.pdf (Page 40)\n",
      "\n",
      "\n",
      "------------------------------------------------------------\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Test queries with citations\n",
    "citation_queries = [\"How did Tesla's automotive sales perform in 2023?\"]\n",
    "\n",
    "print(\"📚 **Query Engine with Citations**\\n\")\n",
    "\n",
    "for query in citation_queries:\n",
    "    print(f\"**Q: {query}**\")\n",
    "    response = await citation_query_engine.aquery(query)\n",
    "\n",
    "    # Process and display the response with citations\n",
    "    content_with_citations = process_citations_with_sources(response)\n",
    "    print(f\"**A:** {content_with_citations}\\n\")\n",
    "    print(\"-\" * 60 + \"\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "In this notebook, we've explored LlamaCloudIndex capabilities in a structured way:\n",
    "\n",
    "### 🚀 Basics Covered:\n",
    "1. **✅ Index Creation**: Built a managed index with 10 financial documents\n",
    "2. **✅ Chunk Retrieval**: Standard retrieval for specific information\n",
    "3. **✅ Simple Query Engine**: Basic RAG without complexity\n",
    "4. **✅ Basic Agent**: FunctionAgent with conversational capability\n",
    "\n",
    "### 🎯 Advanced Features:\n",
    "1. **✅ File-Level Retrieval**: Comprehensive document-level analysis\n",
    "2. **✅ Smart Agent**: Intelligent tool selection between retrieval strategies\n",
    "3. **✅ Citations**: Enhanced transparency with source linking\n",
    "\n",
    "### Key Takeaways:\n",
    "\n",
    "- **Progressive Learning**: Start simple, then add complexity\n",
    "- **LlamaCloudIndex** provides enterprise-grade document search\n",
    "- **Multiple Retrieval Modes** optimize for different query types\n",
    "- **FunctionAgent Integration** uses LLM's native function calling for efficiency\n",
    "- **Citations** add transparency and trust\n",
    "\n",
    "### Next Steps:\n",
    "\n",
    "- Experiment with different retrieval parameters\n",
    "- Try other document types or domains\n",
    "- Build custom workflows and integrations\n",
    "- Explore advanced agent patterns\n",
    "\n",
    "For more examples and documentation:\n",
    "- [LlamaCloudIndex Documentation](https://docs.cloud.llamaindex.ai)\n",
    "- [LlamaIndex Core Documentation](https://docs.llamaindex.ai)\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
